Delegate nnmCorrect() to the NPM package - #521

Summary

• nnmCorrect() (in R/pgx-correct.R) and NPM::NPmatch() (https://github.com/bigomics/NPM) are the same nearest-pair-matching batch correction algorithm, maintained as two separately-drifting implementations. Replace nnmCorrect()'s body with a thin wrapper delegating to NPM::NPmatch(), preserving the original argument names (use.covariates) so existing callers throughout playbase (pgx.superBatchCorrect, runBatchCorrectionMethods, etc.) are unaffected.
• This pulls in NPM's exact closed-form replacement for the limma::removeBatchEffect() pairing-effect-removal step (mathematically identical, not an approximation), which is much faster because it avoids fitting a regression with one factor level per sample -- the cost that made nnmCorrect slow as sample count and/or number of condition groups grew.
• Adds NPM to Imports and to Remotes (url::https://github.com/bigomics/NPM/archive/HEAD.zip), following the existing pattern used for other bigomics GitHub packages (playdata, plaid, metaLINCS).
• nnmCorrect2() is left untouched -- it's a genuinely different, SVD-compressed-covariate approximation, not superseded by this change (see below).

Why

• nnmCorrect's dominant cost is limma::removeBatchEffect(full.X, batch = full.pairs, design = design), where full.pairs has one factor level per original sample. Because the pairing construction always produces a complete, balanced two-way layout (full.pairs x full.y), the OLS batch coefficient this regression fits collapses to a closed form -- each sample's own mean deviation from the grand mean -- computable with a few vectorised matrix subtractions instead of an n-level factor regression.
• Benchmarked against nnmCorrect2 (which tackles the same slowness via per-group KNN + truncated-SVD-compressed covariates): the closed-form fix is faster in every case tested and is exact, whereas nnmCorrect2's output reaches only ~0.85 median gene-wise correlation with the exact result (max deviation > 2x the data's SD on GSE10846) -- consistent with it being harder to control/tending to overcorrect in practice.

Speed (output numerically identical, diffs ~1e-12/4e-13 -- floating-point noise, not an approximation)

Real data, GSE10846 (n=350 samples):

Synthetic, scaling with number of condition groups g (n=400 fixed, knn=1):

Synthetic, scaling with sample count n (g=4 fixed, knn=1):

The speedup grows with both n and g -- exactly the two dimensions along which nnmCorrect used to get slow -- because the old cost was dominated by an n-level factor regression that the closed form eliminates.

Test plan

• Verified the new nnmCorrect() wrapper produces output numerically identical (diffs ~1e-12/4e-13, floating-point noise) to the original inline implementation on GSE10846, at both knn=1 and the default knn=2
• Run the existing playbase test suite / pgx.superBatchCorrect end-to-end with bc="NPM" on a real project
• Confirm remotes::install_deps() / CI can resolve the new NPM dependency from the Remotes: URL

🤖 Generated with Claude Code

https://claude.ai/code/session_01KRrp7pzhFakWWzbD9j1i5R